{{indexmenu_n>3}}

====== Connections ======

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-icon.png}}

{{:opencpn:manual_basic:toolbar:options:connections:tb-opt-conn-net-1.png?600}}

===== Features and Improvements =====

OpenCPN can use a number of different data sources for navigation and environment.

Connection to such a source is set up using this interface.

This applies to navigation data to OpenCPN itself as well as navigation and environment data to plugins.

Data sources can be connected using different types of connections. It can be serial (USB, RS232) or network. Networks can also be available with different variants such as internet protocol-IP (UDP, TCP) or CanBus for some operating systems.

Each data source can use different types of standards to transmit information. OpenCPN supports receiving data according to the following standards:\\
NMEA0183 (N0183), NMEA2000 (N2k) and SignalK (SK).

OpenCPN has a built-in multiplexer where all incoming and outgoing data is distributed.\\
Data from OpenCPN and plugins in the N0183 format can be sent out to various external users. For example, an autopilot.\\
The multiplexer can also filter input and output of N0183 data.

OpenCPN use a prioritization function for navigation data. Only one source of position data is used at a time. "First in, first out" but it can be adjusted by the user. See more details below.

Set-up of incoming and outgoing data from different sources and to consumers is managed using the connection window.\\
Plugins can also internally send data to OpenCPN multiplexer. One example could be VDR, voyage data recorder. Such data is not handled by this interface.

For further details see the table of contents below.

===== Contents =====

//[[:opencpn:opencpn_user_manual:options_setting:connections#connections_window|Connections Window]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#example_data_connections_window|Example Data Connections Window]]\\
[[:opencpn:manual_basic:toolbar:options:connections:priority#data_priority|Adjust data priority scheme]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#filter_nmea_course_and_speed_data|Filter NMEA Course and Speed Data]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#show_nmea_debug_window|Show NMEA Debug Window]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#data_connections_-_add_and_remove|Data Connections - Add and Remove]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#add_a_serial_connection|Add a Serial Connection]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#linux_serial_connections|Linux Serial Connections]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#add_a_network_connection|Add a Network Connection]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#network_gpsd_connection|Network GPSD connection]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#connections_filter|Connections Filter]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#input_filtering|Input Filtering]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#output_filtering|Output Filtering]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#connection_notes|Connection Notes]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#sending_an_active_route_to_an_autopilot|Sending an Active Route to an Autopilot]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#sending_routes_and_waypoints_to_a_gps|Sending Routes and Waypoints to a GPS]]\\
[[:opencpn:opencpn_user_manual:options_setting:connections#broadcast_and_multicast|Broadcast and Multicast]]//

===== Connections Window =====

All this is different from the logic in earlier versions of OpenCPN. From version 3.2, there is no defined "autopilot" port. The autopilot is simply connected to any available output- enabled data-stream, and gets everything on the bus, subject to user specified output filtering. There is no specific "shared" AIS and GPS port, as all ports are shared.

{{:opencpn:manual_basic:toolbar:options:connections:tb-opt-conn-filtering.png?600}}

The key point to keep in mind with this new setup is the complete orthogonality between message sources, message destinations, and transport media. All messages come and go from an internal "bus", and all internal modules have access to all messages. Any message can be received, and possibly re-transmitted according to the configuration established. If the messages get onto the bus,

OpenCPN will do the right thing. For example, if it is an AIS message, the AIS module will get the message and act accordingly. Plugins also get all messages.

===== Example Data Connections Window =====

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-data-conn-window.png?600}}

To get a taste of what can be done, we start with a lab scenario. In the screen-shot above, four Data Ports are enabled.

  * **GPSD on localhost port 2947**
  * **/dev/ttyUSB1 as ais port**
  * **output port**  to a computer on the local network
  * **San Fransisco AIS**  feed.
**Note that the connections are automatically sorted**  in order of the priority setting The picture is from a Linux computer, but the receiving box is an Win XP. Both boxes are configured to use the same broadcasting address '192.168.0.255' on the local network, using the default 10110 port. Note that **UDP**, and not TCP, is used. OpenCPN on the XP box receives and shows all info from the three first ports and even data from the VDR plugin, if it's running. //All input sources are merged together and available to transmit to an external computer. Every computer on-board can be used as a repeater to the main box!//

**Note that in this scenario the UDP connection is output only**. In previous releases of OpenCPN all UDP data connections would read data as well as write. This is a possible configuration in the current release but neither required nor generally desirable. If a broadcast connection is read/write, all data written will be read back leading to the potential for data loops.

  * To avoid this, the priority of any read/write broadcast connection should be set lower than that of any other interface on which OpenCPN receives data for re-distribution over that interface.
  * For most purposes **setting a broadcast connection to either read or write is the preferable solution**.
  * The San Francisco AIS feed has now changed to ip address 76.103.90.196, also on port 9009.

There is no advantage to using a broadcast address on the local network with just a few computers. It's as easy to just specify the addresses of the receiving computers as outgoing connections on the transmitting computer. The "receivers" specify the "transmitter" as address for a connection.

In real life, **a common setup**  will include input from GPS, AIS and output to an Autopilot. If your GPS produces GPRMC, then this will be automatically shipped to the autopilot.

  * Everything on the internal multiplex bus will be sent to the output port that the autopilot is connected to, even if a route is inactive.
  * If, a route is active, OpenCPN will create and send NMEA (EC)RMC sentences to output data ports.
  * The only reason OpenCPN "synthesize" an ECRMC sentence is to cover those odd cases when there is no other source of RMC in the system, and the Autopilot wants variation, SOG, etc. This might be the case if an older GPS produces GPGLL alone, for instance, which has no var. There is no "new" information in the transmitted, synthesized ECRMC.
  * The autopilot might be complaining that it is getting RMC information from two different talkers (GP and EC) at the same time, and cannot decide what to do. The easiest solution if don't like the ECRMC, is to filter it out of the output stream of the port connected to the autopilot. Or choose a filter to allow only GPRMC and ECRMB for this port.

===== Filter NMEA Course and Speed Data =====

Providing a rolling average of COG/SOG, with configurable sampling period. This feature is useful, for example, if you find that course and speed from the gps is varying erratically due to the sea state. The Dashboard plugin is not affected by this setting - COG and SOG are updated about once per second.

{{:opencpn:manual_basic:toolbar:options:connections:tb-opt-con-nmea0183-debug-win.png?600}}

===== Show NMEA Debug Window =====

If you check this box you will get a window that shows the NMEA data sentences coming into or going out from OpenCPN. In the picture above we can see the color-coding at work. Messages in red could occur as well, and indicates a transmit error. Connections Priority change messages, will also be printed to the NMEA Debug Window. The reason that AIVDM messages are both dropped and appear as "Output message", is that there is more than one source for this message, and the filter just applies to one source.

**Have a look at the page NMEA Sentences**  to see which messages are understood. OpenCPN generally does not care about the Talker ID, the first two letters in the message type. $GPGGA above, is the talker GP = the gps, sending a GGA = position message, for example. At the end of each sentence there is a "*" followed by a calculated checksum.

__**To see all messages**__  it's important to close the Options dialog completely, while leaving the NMEA Debug window open. //The ECAPB sentences etc, will not appear while the Connections dialog box is open as autopilot output is disabled during this time.//

__**Known issues:**__  The pause button only works if the main Options dialog is closed. In Linux, the debug window can only be closed by unticking the //Show NMEA Debug Window//  box, unless the the main **Options**  dialog is closed.

If there are NMEA sentences in the debug window, then OpenCPN has opened the port set in the Data Connections. Note that the source of each NMEA sentence is printed after the time stamp o each line. If your GPS port is configured, and there is no "red" boat, then the only reasons are: no gps fix or wrong sentence configuration from the GPS.

Messages originating from **GPSD**  or the VDR (Voyage Data Recorder plugin) will also show up in the debug window.

**For simple NMEA data stream debugging**, add the following to your **opencpn.ini**  file:Under //[Settings]//  add a line //DebugNMEA=1500//  This will provide up to 1500 debug messages pertaining to NMEA traffic to the //opencpn.log//.

**Format uploads for FurunoGP3Xinputfiltering**: If the special Furuno gps protocol is needed, tick this box. The reason is that Furuno uses their own version of NMEA for uploading routes. Furuno GPS users take note. It is now allowed to use a numeric, two digit OpenCPN route name (e.g. 10, 21, etc).

Use GarminGRMN (Host) mode for uploads. Make sure that this box is ticked, if you have a Garmin GPS. The reason for this is that Garmin units cannot accept route uploads via standard NMEA0183. This is a "design feature" of all Garmin receivers.

Use magnetic bearings in output sentence ECAPB. Some autopilots, among them Simrad, require navigational bearings, contained in the APB sentence, to be transmitted as Magnetic bearings rather than as True bearings, OpenCPNs default.

===== Data Connections - Add and Remove =====

Two Buttons "Add Connections" and "Remove Connections", to the right of the Connections window are the key to this whole tab.

The enable choice at the start of each connection line, is handy to organize connections, but still only use those that are needed for the moment. Tick or un-tick, and then press "Apply", to activate the setting.

A connection can be used for input and output at the same time, with the reservation that they have to use the same Baud rate. For more details, read on.

When pressing "Add Connections" two basic choices are given, a serial or a network connection.

===== Add a Serial Connection =====

{{:opencpn:manual_basic:toolbar:options:connections:tb-opt-conn-comm-add-serial-connection.png}}

**DataPort**: Pick a port by pressing the \/ o the right side of the field. If the port you are looking for does not appear in the selection, write the correct port yourself in this field. [2021-05-13 Two users ([[https://www.cruisersforum.com/forums/f134/setting-up-opencpn-rookie-with-an-issue-249054.html|1]], [[https://www.cruisersforum.com/forums/f134/gps-drivers-not-on-globalsat-website-250626.html|2]]) have reported problems with manual entry of the com port that were corrected by using the drop down selection of the same port]

**Baud Rate**: This is normally 4800 for GPS and 38400 for AIS, but check the documentation for the connected device. It's important to get this right and not just guess.

**Protocol**: For future use, as only NMEA 0183 works, for now.

**Priority**: Higher number equals Higher priority. The priority is set for each NMEA sentence individually. As long as a higher priority stream is available it's used. If this fails the next stream in line, with lower priority, kicks in and is used, until a higher priority stream appears. The present filter does not handle the case where, for example position messages, are received from different sentences.As an example, GPGLL and GPRMC both transmits the position information. The last received of either message will be used.

**Control Checksum**. At the end of each NMEA sentence is a checksum, that makes sure that sentences are correctly received. This box is ticked by default, as OpenCPN calculates the checksum and compares it to the received checksum. Only sentences with a valid checksum are passed through. Un-ticking may help, if an application calculates checksums incorrectly or if the checksums are missing.

Use **Garmin(GRMN)**  mode for input: Make sure that this box is ticked, if you have a Garmin GPS set to this mode. The reason is that Garmin uses their own serial protocol.

**Receive input**  on this Port Greyed out here as it only applies to a network connection. see more below.

**Output on this port**  (as Autopilot or NMEA repeater ): Tick this box if the connection will be used for output. A common case is sending NMEA to an Autopilot. * Talker ID solves the problem where some "temperamental" devices, which should accept given sentences irrespective of the talker ID, in fact only accept for example GPRMC and not ECRMC

**APB bearing precision**  is greyed out unless "Output on this port" is checked. APB is the NMEA sentence "Autopilot Sentence 'B'". The precision can be set to between 0 and 4 decimals, were 3 is the default. Some autopilots requires a different precision than the default, to work. Check your AP documentation.

  * Note: The **APB bearing precision**  (or NMEAAPBPrecision in Opencpn.ini file) setting is set in the Options > Connections settings page for connections that have outgoing messages. The precision is applied in the src/nmea0183/ apb.cpp file and is applied to:
      * CrossTrackErrorMagnitude
      * BearingOriginToDestination
      * BearingPresentPositionToDestination
      * HeadingToSteer
  * This change was made as some auto pilots are limited in the precision they can accept in the APB message. So all other messages and internally the precision is not changed. There is no change to the XTE message as that was not requested at the time. "XTE - Measured cross track error" NMEA message, that is a part of the APB message is not adjusted by the APB bearing precision setting.

==== Linux Serial Connections ====

Make sure that you belong to the "dialout" group. To find out, run the "$groups" command. If you're not in "dialout", add yourself with the command "$sudo usermod -a -G dialout $USER". Logout of your current session for group changes to take effect. Check this straight away, it will save you from frustration later on. If there is a problem connecting the GPS to a physical port, such as /dev/ttyS0, the reason is probably that you don't belong to "dialout". OpenCPN will display a warning, once per session, if you try to configure a serial connection, or starts the program with an active serial connection, and don't belong to the right group.

group.jpeg

Red Hat based Linux versions are using the "uucp" group. Check what applies to your version of Linux, by using the return from the command stat -c %G `ls /dev/*|grep -m1 tty[A-Z,a-z][0] If the return is "root", upgrade to a contemporary Linux version.

===== Add a Network Connection =====

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-network_0.png?nolink&600x403}}

==== Protocol Choices: TCP, UDP or GPSD ====

=== TCP ===

A "connection-oriented" protocol which provides a reliable link between two network endpoints. TCP ensures that any network packets lost in transit are re-transmitted. Internet AIS servers normally accept TCP connections as do many serial-to-network/wifi devices.

**To make a connection to a remote TCP server**, enter its //IP address//  or //hostname//  in the "**Address**" box and the TCP port on which the server listens in the "**DataPort**" box. Many devices use a non-standard TCP port rather than OpenCPN's standard 10110, so do check the server's documentation.

If "**0.0.0.0**" is entered in the **Address**  box, OpenCPN will act as a **TCP server**  accepting a connection from a **remote TCP client**. OpenCPN will **listen**  on all its host computer's network interfaces for **TCP connections**  to the port specified in the "**DataPort**" field. There should normally be no reason to select a "**DataPort**" value other than the **standard 10110**  unless multiple servers are required:

  * In the current implementation a single data connection can accept only one client.
  * If multiple clients wish to connect to OpenCPN, a dedicated data connection must be provided for each and each data connection must have a different DataPort.

=== UDP ===

A method of transmitting data as simple "**datagrams**" without negotiating a connection between two endpoints. It involves no detection and retransmission of data lost in the network. Within a small home/boat network such data loss should not normally occur and in any case, NMEA data is generally updated by "talkers" on a regular basis. Unlike TCP which involves a connection between two endpoints, UDP data may be received by many "listeners".

  * For UDP input no IP is required. Try just going with the port. 0.0.0.0 :1456
  * For UDP NMEA senders if you make the last octet of the IP address 255 then messages should go to all devices on that subnet. In OpenCPN the address should be 0.0.0.0 (don’t care) and the port number must match the sending port number. Also, any router in between the sender and O must be configured to not block the assigned port number. Sometimes a really high port number (like 10110) will not be blocked.

An** OpenCPN UDP data connection**  will listen for data destined for the **specified DataPort**  on any system interface or the broadcast address of any connected network.

  * If you don't need to receive multicast data or transmit any data, you may enter "**0.0.0.0**" in the "Address" box, if you are unsure of what to enter there. Alternatively you may specify the address on which you //intend to receive data//. In both cases behavior will be the same.
  * If you wish to receive multicast data you must enter the multicast address to which those data are being sent or the system will not see them.
  * If you wish to transmit any data ("**Output on this port**" checked) you must //put the address you wish to send data to in the "Address" box//.
  * In all cases (transmit, receive or both) the DataPort must be specified.

For more information about broadcast and multicast, see [[:opencpn:opencpn_user_manual:options_setting:connections#broadcast_and_multicast|Broadcast and Multicast below]].

=== GPSD ===

A Unix/Linux gps server, which means that several different applications can share one gps receiver. Linux users have the choice between using serial or GPSD connections for their gps input.

  * **Ubuntu users take note!**  If gpsd is installed - use it. If you prefer a serial connection, un-install gpsd. The reason is that gpsd starts automatically when,for example, an USB gps is connected. This will block the serial port that the gps communicates with( /dev/ttyUSB0 in many cases), hence no separate serial connection to the gps is possible. So it's an either or situation.
  * **OpenCPN also has support for Windows clients.**  So a windows computer should be able to connect to GPSD running somewhere on a network (testing), as an alternative to an UDP connection, described earlier. * Address: The network address to connect to. In the example above we used the broadcast address for convenience, but specifying host to send to, and host to receive from, works as well.
**Port**: The port to connect to on the network address. The default port for UDP is 10110. Port 10110 is designated by IANA for "NMEA-0183 Navigational Data". There should not be any reason to change this port, but it is possible. See below. The default port for GPSD is 2947. Do not change this!

  * For your own local connections use port-numbers greater than 1023 and avoid ports used by other applications. //Ports in the range 49152 through 65535 are not assigned to other applications and should be OK//. Make sure that no firewall is blocking the port you pick.

===== Network GPSD connection =====

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-gpsd-con1.png?nolink&600x210}}

When connecting to GPSD, running on your local computer, use the settings shown above.

===== Connections Filter =====

For each source line in the data connection windows, it's possible to specify exactly which NMEA sentences to receive, and which ones to drop. Similarly it's possible to control exactly which sentences to send out to, for example, an autopilot.

The applied filters for each connection are stated in in the "Filters" column in the Data Connection window. The default for a connection is no filters at all. * The set filters applies to both the core program and the plugins.

Filtering can be observed in real time, through color coding in the Debug Window.

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-filtering.png?nolink&626x189}}

**Accept only sentences**: Either base your filtering on stating which sentences to accept or which to ignore.

**Ignore sentences**: Same as above. To select filters press the button. The dialog below becomes available.

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-sentence-filters.png?nolink&280x420}}

A lot of NMEA sentences are listed. You may have to add a NMEA sentence that is not in the list. Just tick the box to select a sentence. "Select All" or "Clear All" are also available. For sentences not listed press "Add", and enter a new NMEA sentence.

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-sentence-filters1.png?nolink&313x97}}

Your entry must conform to these rules.

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-sentence-filters2.png?nolink&459x166}}

When you are finished, press "OK", your new entry will appear at the bottom of the list of NMEA sentences to filter. It will already be ticked, so just press "OK" until you are back in the original Connections tab. Now press "Apply". The implemented filtering should now be visible on the connection line. For more, see below

**Receive input on this port**: This box should be ticked if you want to receive receive data on this connection. If the connection will only be used to output to other devices it should not be ticked. If you wish to broadcast UDP data for consumption by other devices or programs, leaving this box unticked will save you having to worry setting the priority of the connection to avoid data loops.

**Output on this port**  (as Autopilot or NMEA repeater ): Tick this box if the connection will be used for output. A common case is sending NMEA to an Autopilot. * APB bearing precision is greyed out unless "Output on this port" is checked. APB is the NMEA sentence "Autopilot Sentence 'B'". The precision can be set to between 0 and 4 decimals, were 3 is the default. Some autopilots requires a different precision than the default, to work. Check your AP documentation and see Note below.

OpenCPN creates and sends the NMEA ECRMB and ECRMC sentences to the A/P output port when a route is activated. If variation is not otherwise present, OpenCPN includes variation, coming from the WMM plugin, if installed and enabled.

Note: The "APB bearing precision" (or NMEAAPBPrecision in Opencpn.ini file) setting is set in the Connections settings page for connections that have outgoing messages. The precision is applied in the src/nmea0183/ apb.cpp file and is applied to:

  * CrossTrackErrorMagnitude
  * BearingOriginToDestination
  * BearingPresentPositionToDestination
  * HeadingToSteer
  * This change was made as some auto pilots are limited in the precision they can accept in the APB message. So all other messages and internally the precision is not changed. There is no change to the XTE message as that was not requested at the time. "XTE - Measured cross track error" NMEA message, that is a part of the APB message is not adjusted by the APB bearing precision setting.

FIXME <nowiki>{{opencpn:manual:action-filter.png?nolink&28×30}}</nowiki>

===== Input Filtering =====

Some examples to illustrate how things works.

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-in1.png?nolink&600x89}}

Accepting the filter above leads to this in the filter column on the connection line:

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-in11.png?nolink&217x21}}

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-in2.png?nolink&614x95}} \\ If "Ignore sentences" is marked instead, the line looks like this: \\ {{:opencpn:manual_basic:toolbar:options:tb-opt-conn-in22.png?nolink&230x21}}

===== Output Filtering =====

Similar to input filtering above. \\ {{:opencpn:manual_basic:toolbar:options:tb-opt-conn-in2.png?nolink&614x95}}

Transmitting three sentences.

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-out22.png?nolink&234x23}}

Another Example of Output Filtering

{{:opencpn:manual_basic:toolbar:options:tb-opt-conn-output-filter-sentence.png?nolink&550x305}} \\ **Feature:**  Can now select the NMEA talker ID of sentences output by OpenCPN on a given port.

**Situation:**  OpenCPN (correctly) outputs its NMEA sentences with the "EC" talker ID as is normal and expected behavior (see below).

**Problem :**  Some "temperamental" devices which should accept given sentences irrespective of the talker ID in fact only accept for example GPRMC and not ECRMC.

**Example:**  An Icom VHF is a such example. and because the multiplexer has been set to give precedence to nav info provided by OpenCPN, rather than the GPS, the result is that when OpenCPN is driving the autopilot, the VHF does not receive any position anymore for its DSC feature. Safety-wise, this is not desirable.

**Solution:**  Being able to either change the ECRMC sentences into GPRMC, or duplicate ECRMC on the output port should solve the issue.

**AutoPilot Compatibility with respect to heading**

- From O's point of view, the basic sentence the AP needs is RMB (It already contains the XTE information), most AP work with jut this sentence being output. - If this is not enough, and especially if the pilot is Simrad / B&G with simnet, APB must be added so that the gateway adds the PGN "heading / track control). Cruiser's Forum has an excellent thread discussion testing a N2K AP, using various devices, a summary [[https://www.cruisersforum.com/forums/f134/actisense-nmea-2000-and-autopilot-issues-with-raspberry-pi-open-cpn-261664.html#post3617267|post #106 ]]but the entire thread is informative.

